docs: Add ARCHITECTURE.md with diagram of components #615

cliffmccarthy · 2025-08-11T15:07:18Z

For starters, this file is just a diagram of components of a chatmail server. In the future, this document can grow into a more complete description of the architecture of the server, the deployment process, and the design intent behind what is and isn't in the code base.
The name ARCHITECTURE.md is inspired by this article, which also has good suggestions about what to put in the file: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html

cliffmccarthy · 2025-08-11T15:09:21Z

The current revision is a rough draft, and will probably be revised further as I study the code more.

hpk42

Sounds good as a start. thanks!

hpk42 · 2025-08-15T18:36:53Z

ARCHITECTURE.md

@@ -0,0 +1,37 @@
+This diagram shows components of the chatmail server:


Please qualify this sentence that's it's a draft overview as of mid August 2025.

Thanks for the review! I updated the text as you suggested. I also added labels to some of the arrows to indicate the ports and sockets that the components communicate by.

- For starters, this file is just a diagram of components of a chatmail server. In the future, this document can grow into a more complete description of the architecture of the server, the deployment process, and the design intent behind what is and isn't in the code base. - The name ARCHITECTURE.md is inspired by this article, which also has good suggestions about what to put in the file: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html

- Suggested in review by hpk42.

missytake

This is a great start, the only missing things I can think of are opendkim and the lastlogin service, but we can also merge it as it is and add them later :)

I added some suggestions, which would make more sense for me - but as this diagram is not so I can understand it, but for newcomers, I'd leave it to you which you want to adapt :)

For others looking at this, a preview is at https://github.com/cliffmccarthy/chatmail-relay/blob/architecture-doc/ARCHITECTURE.md

missytake · 2025-08-16T07:15:49Z

ARCHITECTURE.md

+    chatmail-metrics --> /var/www/html;
+    acmetool --> certs;
+    acmetool --> acmetool-redirector;
+    acmetool-redirector --> certs;


Suggested change

acmetool-redirector --> certs;

acmetool-redirector --> nginx;

I would argue that acmetool-redirector doesn't actually have much to do with certs, and mostly just redirects traffic to nginx?

missytake · 2025-08-16T07:16:30Z

ARCHITECTURE.md

+    acmetool --> certs;
+    acmetool --> acmetool-redirector;
+    acmetool-redirector --> certs;
+    nginx --> /var/www/html;


Suggested change

nginx --> /var/www/html;

nginx --> |8443|/var/www/html;

We could include that port 8443 is needed to show the webroot directory :)

missytake · 2025-08-16T07:18:18Z

ARCHITECTURE.md

+    acmetool-redirector --> certs;
+    nginx --> /var/www/html;
+    nginx --> certs;
+    nginx --> newemail.py;


Suggested change

nginx --> newemail.py;

nginx --> |8443|newemail.py;

same for newemail.py :)

missytake · 2025-08-16T07:18:45Z

ARCHITECTURE.md

+    acmetool --> acmetool-redirector;
+    acmetool-redirector --> certs;
+    nginx --> /var/www/html;
+    nginx --> certs;


Suggested change

nginx --> certs;

certs --> nginx;

And one could argue that nginx is dependent on the certs, not the other way round.

missytake · 2025-08-16T07:19:37Z

ARCHITECTURE.md

+    nginx --> |993|dovecot;
+    autoconfig.xml --> postfix;
+    autoconfig.xml --> dovecot;
+    postfix --> certs;


Suggested change

postfix --> certs;

certs --> postfix;

same for postfix...

missytake · 2025-08-16T07:19:50Z

ARCHITECTURE.md

+    postfix --> |10080,10081|filtermail;
+    postfix --> echobot;
+    postfix --> |doveauth.socket|doveauth;
+    dovecot --> certs;


Suggested change

dovecot --> certs;

certs --> dovecot;

...and dovecot ;)

missytake · 2025-08-16T07:24:56Z

ARCHITECTURE.md

+    cron --> acmetool;
+    cron --> chatmail-metrics;
+    chatmail-metrics --> /var/www/html;
+    acmetool --> certs;


Suggested change

acmetool --> certs;

acmetool --> /var/lib/acme;

For /home/vmail and /var/www/html we also talk about the path, because they contain state... we could do that for the certs as well :) that would make it clearer what to backup/manage. maybe TLS certs /var/lib/acme, Users /home/vmail, and Website /var/www/html? That would make it more obvious what the paths contain.

missytake · 2025-08-16T08:09:58Z

Let me know what changes you want to include, then I'll merge this :)

cliffmccarthy · 2025-08-17T15:28:37Z

Thanks for all the review feedback! I will submit a new revision in the next day or two.

- Implemented changes suggested in review by missytake: - Removed relation between acmetool-redirector and certs. - Added internal nginx listening on port 8443. - Changed direction of arrows between certs and the services that use them. This makes the arrow show the direction of information flow, rather than a "depends on" relation. - For filesystem paths, added a descriptive name to the node. - Replaced most arrows with plain lines, to simply show that a relationship exists between the two nodes. This also reduces visual clutter, since the graph is pretty dense with information already. - Split nginx and certs into two nodes, to reduce entanglement in the graph. These "linked" nodes are given a different shape and filled with a different colour, to highlight the fact that they are the same node. - Revised text about the meaning of edges in the graph.

cliffmccarthy · 2025-08-18T20:16:49Z

I tried to incorporate all your suggestions in the latest revision. This isn't perfect, but it's starting to push the limits of what can be reasonably expressed in a mermaid diagram. I'm open to any suggestions about better colours for the duplicated nodes. I do want to incorporate opendkim and lastlogin, but that will probably jumble the layout again, leading to another round of graph-hacking. I'll take that up in another revision (possibly in this PR if it's still open when I get to it).

Here are the details from the latest commit message:

Implemented changes suggested in review by missytake:
- Removed relation between acmetool-redirector and certs.
- Added internal nginx listening on port 8443.
- Changed direction of arrows between certs and the services that use them. This makes the arrow show the direction of information flow, rather than a "depends on" relation.
- For filesystem paths, added a descriptive name to the node.
Replaced most arrows with plain lines, to simply show that a relationship exists between the two nodes. This also reduces visual clutter, since the graph is pretty dense with information already.
Split nginx and certs into two nodes, to reduce entanglement in the graph. These "linked" nodes are given a different shape and filled with a different colour, to highlight the fact that they are the same node.
Revised text about the meaning of edges in the graph.

missytake · 2025-08-19T11:04:25Z

Thanks, let's merge this for now :) I also have some ideas, which go more into the direction of "depending on" than "information flow" actually. Might open a PR about it :)

cliffmccarthy mentioned this pull request Aug 11, 2025

Add installation using Docker Compose and many other improvements for implementation in Docker. #614

Open

hpk42 approved these changes Aug 15, 2025

View reviewed changes

cliffmccarthy added 2 commits August 15, 2025 18:15

docs: Indicate draft status in ARCHITECTURE.md

0c1adff

- Suggested in review by hpk42.

cliffmccarthy force-pushed the architecture-doc branch from c0f630f to 0c1adff Compare August 15, 2025 23:15

missytake approved these changes Aug 16, 2025

View reviewed changes

missytake merged commit 2de8b15 into chatmail:main Aug 19, 2025
2 of 4 checks passed

		@@ -0,0 +1,37 @@
		This diagram shows components of the chatmail server:

	acmetool-redirector --> certs;
	acmetool-redirector --> nginx;

Uh oh!

docs: Add ARCHITECTURE.md with diagram of components #615

docs: Add ARCHITECTURE.md with diagram of components #615

Uh oh!

Conversation

cliffmccarthy commented Aug 11, 2025

Uh oh!

cliffmccarthy commented Aug 11, 2025

Uh oh!

hpk42 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

missytake left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

missytake commented Aug 16, 2025

Uh oh!

cliffmccarthy commented Aug 17, 2025

Uh oh!

cliffmccarthy commented Aug 18, 2025

Uh oh!

missytake commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

missytake left a comment •

edited

Loading

missytake commented Aug 19, 2025 •

edited

Loading